home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / unix / volume16 / spiff / part04 < prev    next >
Encoding:
Internet Message Format  |  1988-11-10  |  26.9 KB

  1. Subject:  v16i070:  Spiff, find approximate differences in files, Part04/04
  2. Newsgroups: comp.sources.unix
  3. Sender: sources
  4. Approved: rsalz@uunet.UU.NET
  5.  
  6. Submitted-by: Daniel W Nachbar <daniel@wind.bellcore.com>
  7. Posting-number: Volume 16, Issue 70
  8. Archive-name: spiff/part04
  9.  
  10. #! /bin/sh
  11. # This is a shell archive.  Remove anything before this line, then unpack
  12. # it by saving it into a file and typing "sh file".  To overwrite existing
  13. # files, type "sh file -c".  You can also feed this as standard input via
  14. # unshar, or by typing "sh <file", e.g..  If this archive is complete, you
  15. # will see the following message at the end:
  16. #        "End of archive 4 (of 4)."
  17. # Contents:  paper.ms
  18. # Wrapped by rsalz@papaya.bbn.com on Fri Nov 11 13:12:27 1988
  19. PATH=/bin:/usr/bin:/usr/ucb ; export PATH
  20. if test -f 'paper.ms' -a "${1}" != "-c" ; then 
  21.   echo shar: Will not clobber existing file \"'paper.ms'\"
  22. else
  23. echo shar: Extracting \"'paper.ms'\" \(25154 characters\)
  24. sed "s/^X//" >'paper.ms' <<'END_OF_FILE'
  25. X.ll 6i
  26. X.nr PO 1.15i
  27. X.nr HM 0i
  28. X.nr FM 1.05i
  29. X.TL
  30. XSPIFF -- A Program for Making Controlled Approximate Comparisons of Files
  31. X.AU
  32. XDaniel Nachbar
  33. X.AI
  34. XSoftware Engineering Research Group
  35. XBell Communications Research
  36. XMorristown, New Jersey
  37. X.AB
  38. XThe well known program 
  39. X.B
  40. Xdiff
  41. X.R
  42. X[1]
  43. Xis inappropriate for some
  44. Xcommon tasks such as comparing the output of floating
  45. Xpoint calculations where roundoff errors
  46. Xlead 
  47. X.B
  48. Xdiff
  49. X.R
  50. Xastray and comparing program source code
  51. Xwhere some differences in the text (such as white space and comments)
  52. Xhave no effect on the operation of the compiled code. A new program,
  53. Xnamed 
  54. X.B
  55. Xspiff,
  56. X.R
  57. Xaddresses these and other similar cases
  58. Xby lexical parsing of the input files and then applying
  59. Xa differencing algorithm to the token sequences.  
  60. X.B
  61. XSpiff
  62. X.R
  63. Xignores differences
  64. Xbetween floating point numbers that are below a user settable tolerance.
  65. XOther features include user settable commenting and literal string
  66. Xconventions and a choice of differencing algorithm.
  67. XThere is also an interactive mode wherein the input texts are displayed
  68. Xwith differences highlighted.  The user can change numeric tolerances
  69. X"on the fly" and 
  70. X.B
  71. Xspiff
  72. X.R
  73. Xwill adjust the highlighting accordingly. 
  74. X.AE
  75. X.SH
  76. XSome Troubles With Diff
  77. X.PP
  78. XOver the past several years, it has been fairly easy to tell when 
  79. Xa new type of computer arrived at a nearby computer center.
  80. XThe best clue was the discordant chorus of
  81. Xgroaning, sighing, gnashing of teeth, pounding of foreheads on desks,
  82. Xand other sounds of distress.  Tracing these noises to their source, one
  83. Xwould find some poor soul in the process of installing
  84. Xa numerical analysis package on the new machine.
  85. X.PP
  86. XOne might expect that "moving up" to a new machine
  87. Xwould be a cause for celebration.
  88. XAfter all, new machines are typically bigger, faster,
  89. Xand better than old machines.
  90. XHowever, the floating point arithmetic on any new machine is frequently
  91. Xslightly different from any old machine.
  92. XAs a consequence,
  93. Xsoftware package test routines produce output that is slightly different,
  94. Xbut still correct, on the new machines.
  95. XSerious troubles appear when the person installing the software package
  96. Xattempts to compare the test output files from two different machines
  97. Xby using a difference finding program such as
  98. X.B
  99. Xdiff.
  100. X.R
  101. XPrograms such as 
  102. X.B
  103. Xdiff
  104. X.R
  105. Xdo a character by character comparison.
  106. X.B
  107. XDiff
  108. X.R
  109. Xfinds a great many differences,  most of which
  110. Xare due to roundoff errors in the least significant digits of floating point
  111. Xnumbers.  Others are the result of differences in the way
  112. Xin which the two test runs
  113. Xhad printed a number (3.4e-1 vs. 0.34).
  114. XIn one case, the test suite for the S statistical analysis package[2],
  115. Xover 1700 floating point numbers are produced
  116. X(per machine). In the eyes of 
  117. X.B
  118. Xdiff,
  119. X.R
  120. Xroughly 1200 of these numbers are different.
  121. XHowever, none of the "differences" are important ones.
  122. XNonetheless, software installers wind up inspecting the output by eye.
  123. X.PP
  124. XA similar problem arises when one attempts to
  125. Xlook for differences between two versions
  126. Xof the same C program.
  127. X.B
  128. XDiff
  129. X.R
  130. Xreports many differences that are not of interest.  In
  131. Xparticular, white space (except inside quotation marks) and
  132. Xanything inside a comment have no effect on the operation of the compiled
  133. Xprogram and are usually not of interest.
  134. X.B
  135. XDiff
  136. X.R
  137. Xdoes have a mode of operation where white space
  138. Xwithin a line (spaces and tabs) can be ignored.
  139. XHowever, differences in the placement of newlines cannot be ignored.
  140. XThis is particularly annoying since C programming
  141. Xstyles differ on whether to place a newline character before or after the '{'
  142. Xcharacters that start blocks.
  143. X.SH
  144. XThe Problem in General Terms
  145. X.PP
  146. XAs already mentioned, programs such as 
  147. X.B
  148. Xdiff
  149. X.R
  150. Xdo
  151. Xa character-by-character comparison of the input files.
  152. XHowever, when it comes to interpreting
  153. Xthe contents of a file (either by a human or by a program)
  154. Xit is almost never the case that characters
  155. Xare treated individually. Rather, characters make up tokens such
  156. Xas words and numbers, or act as separators between these tokens.
  157. XWhen comparing files, one is usually looking for
  158. Xdifferences between these tokens, not the characters that make them up
  159. Xor the characters that separate them.
  160. X.PP
  161. XWhat is needed is a program that first parses the input files
  162. Xinto tokens, and then applies a differencing algorithm to the token
  163. Xsequences. 
  164. XIn addition to finding differences in terms of tokens,
  165. Xit is possible to interpret the tokens and
  166. Xcompare different types of tokens in different ways.  Numbers, for example,
  167. Xcan differ by a lot or a little.\**
  168. X.FS
  169. XCurrent differencing programs do not have such a notion because
  170. Xthe difference between two characters is a binary function.
  171. XTwo characters are the same or they are not.
  172. X.FE
  173. XIt is possible to use a tolerance when comparing two number tokens and
  174. Xreport only those differences that exceed the tolerance.
  175. X.SH
  176. XDesign Issues
  177. X.PP
  178. XA serious design issue for such a program is how
  179. Xcomplex to make the parse.  The
  180. X.I
  181. Xdeeper
  182. X.R
  183. Xone goes in the parsing the larger
  184. Xthe unit of text that can be manipulated.  For instance, if one is looking
  185. Xfor differences in C code, a complete parse tree can be produced and
  186. Xthe differencing algorithm could examine insertion and deletion of entire
  187. Xbranches of the tree.  However, deep parsing requires much more
  188. Xcomplex parsing and slower differencing algorithms.
  189. X.PP
  190. XAnother design issue is deciding how to interpret the tokens.
  191. XCloser interpretation may lead to greater flexibility in comparing tokens, but
  192. Xalso results in a more cumbersome and error-prone implementation.
  193. X.PP
  194. XIn the program described here, we attempt to keep both the depth
  195. Xof the parse and the semantics of the tokens to a minimum.
  196. XThe parse is a simple
  197. Xlexical parse with the input files broken up into one dimensional
  198. Xsequences of numbers, literal strings and white space.
  199. XLiteral strings and white space are not interpreted. Numbers
  200. Xare treated as representing points on the real number line.
  201. X.SH
  202. XDefault Operation
  203. X.PP
  204. X.B
  205. XSpiff\**
  206. X.R
  207. X.FS
  208. XWe picked the name as a way to pay a small tribute to that famous intergalactic
  209. Xadventurer Spaceman Spiff[3].
  210. X.B
  211. XSpiff
  212. X.R
  213. Xis also a contraction of "spiffy diff".
  214. X.FE
  215. Xworks very much like 
  216. X.B
  217. Xdiff.
  218. X.R
  219. XIt reads two files, looks
  220. Xfor differences, and prints a listing of the
  221. Xdifferences in the form of
  222. Xan edit script.\**
  223. X.FS
  224. XAn edit script is a sequence of insertions and deletions
  225. Xthat will transform the first file into the second.
  226. X.FE
  227. XAs already suggested, 
  228. X.B
  229. Xspiff
  230. X.R
  231. Xparses the files into
  232. Xliteral strings and real numbers.
  233. XThe definition of these tokens can be altered somewhat by the user
  234. X(more on this later).  For now, suffice it
  235. Xto say that literals are strings like "cow", "sit",
  236. X"into", etc.  Real numbers look like "1.3", "1.6e-4" and so on.
  237. XAll of the common formats for real numbers are recognized.
  238. XThe only requirements for a string to be
  239. Xtreated as a real number is the presence
  240. Xof a period and at least one digit.
  241. XBy default, a string of digits without a decimal point
  242. X(such as "1988") is not considered to be a real number,
  243. Xbut rather a literal string.\**
  244. XEach non-alphanumeric character (such as #$@^&*)
  245. Xis parsed into a separate literal token.
  246. X.FS 
  247. XInteger numbers are often used as indices, labels, and so on.
  248. XUnder these circumstances, it is more appropriate to treat them as literals.
  249. XOur choice of default was driven by a design goal
  250. Xof having 
  251. X.B
  252. Xspiff
  253. X.R
  254. Xbe very conservative
  255. Xwhen choosing to ignore differences.
  256. X.FE
  257. X.PP
  258. XOnce 
  259. X.B
  260. Xspiff
  261. X.R
  262. Xdetermines the two sequences of tokens,
  263. Xit compares members of the first sequence with
  264. Xmembers of the second sequence.
  265. XIf two tokens are of different types,
  266. X.B
  267. Xspiff
  268. X.R
  269. Xdeems them to be different, regardless of their content.
  270. XIf both tokens are literal tokens, 
  271. X.B
  272. Xspiff
  273. X.R
  274. Xwill deem them
  275. Xto be different if any of their characters differ.
  276. XWhen comparing two real numbers,
  277. X.B
  278. Xspiff
  279. X.R
  280. Xwill deem them to be different only if
  281. Xthe difference in their values exceeds a user settable tolerance.
  282. X.SH
  283. XAltering Spiff's Operation 
  284. X.PP
  285. XTo make 
  286. X.B
  287. Xspiff
  288. X.R
  289. Xmore generally useful, the user can control:
  290. X.IP \(bu
  291. Xhow text strings are parsed into tokens 
  292. X.IP \(bu
  293. Xhow tokens of the same type are compared
  294. X.IP \(bu
  295. Xthe choice of differencing algorithm used
  296. X.IP \(bu
  297. Xand the granularity of edit considered by the differencing algorithm.
  298. X.LP
  299. X.PP
  300. XThese features are described next.
  301. X.SH
  302. XAltering the Parse
  303. X.PP
  304. XThe operation of the parser can be altered in several ways.
  305. XThe user can specify that delimited sections of text are to be ignored
  306. Xcompletely.  This is useful for selectively ignoring the contents of
  307. Xcomments in programs.  Similarly, the user can specify that
  308. Xdelimited sections of text (including white space)
  309. Xbe treated as a single literal token.  So, literal strings in program
  310. Xtext can be treated appropriately.
  311. XMultiple sets of
  312. Xdelimiters may be specified at once (to handle cases such as the
  313. XModula-2 programming language
  314. Xwhere there are two ways to specify quoted strings). At present,
  315. Xthe delimiters must be fixed string (possibly restricted to the
  316. Xbeginning of the line) or end of line.
  317. XAs a consequence of the mechanism for specifying literal strings,
  318. Xmulticharacter operators (such as the += operator in C)
  319. Xcan be parsed into a single token.
  320. X.PP
  321. XAs yet, no provision is made for allowing delimiter
  322. Xspecification in terms of regular expressions.  This omission 
  323. Xwas made for the sake of simplifying the parser.
  324. XNothing prevents the addition of regular expressions in the
  325. Xfuture.  However, the simple mechanism
  326. Xalready in place handles the literal string and commenting conventions
  327. Xfor most well known programming languages.\**
  328. X.FS
  329. XSee the manual page in the appendix for examples of handling
  330. XC, Bourne Shell, Fortran, Lisp, Pascal, and Modula-2.  The only
  331. Xcases that are known not to work are comments in BASIC and
  332. XHollerith strings in Fortran.
  333. X.FE
  334. X.PP
  335. XIn addition to controlling literal string and comments, the user
  336. Xmay also specify whether to treat white space characters as any other
  337. Xnon-alphanumeric character (in other words, parse each white space
  338. Xcharacter into its own literal token),
  339. Xwhether to parse sign markers as part
  340. Xof the number that they precede or as separate tokens, whether
  341. Xto treat numbers without printed decimal markers (e.g. "1988") 
  342. Xas real numbers rather than as literal strings, and whether
  343. Xto parse real numbers into literal tokens.
  344. X.SH
  345. XAltering the Comparison of Individual Tokens
  346. X.PP
  347. XAs mentioned earlier, the user can set a tolerance below which differences
  348. Xbetween real numbers are ignored.  
  349. X.B
  350. XSpiff
  351. X.R
  352. Xallows two kinds of tolerances:
  353. Xabsolute and relative. 
  354. XSpecifying an absolute tolerance will cause 
  355. X.B
  356. Xspiff
  357. X.R
  358. Xto ignore differences
  359. Xthat are less than the specified value.
  360. XFor instance, specifying an absolute tolerance of 0.01 will
  361. Xcause only those differences greater than or equal to 0.01 to be reported.
  362. XSpecifying a relative tolerance will cause 
  363. X.B
  364. Xspiff
  365. X.R
  366. Xto ignore differences that are
  367. Xsmaller than some fraction of the number of larger magnitude.
  368. XSpecifically, the value of the tolerance is interpreted
  369. Xas a fraction of the larger (in absolute terms) 
  370. Xof the two floating point numbers being compared.
  371. XFor example,
  372. Xspecifying a relative tolerance of 0.1
  373. Xwill cause the two floating point numbers 1.0 and 0.91 to be deemed within
  374. Xtolerance. The numbers 1.0 and 0.9 will be outside the tolerance.
  375. XAbsolute and relative tolerances can be OR'ed together.  In fact,
  376. Xthe most effective way to ignore differences that are due to roundoff errors
  377. Xin floating point calculations is to use both
  378. Xa relative tolerance (to handle limits in precision) as well as an absolute
  379. Xtolerance (to handle cases when one number is zero and the other number is
  380. Xalmost zero).\**
  381. X.FS
  382. XAll numbers differ from zero by 100% of their magnitude.  Thus, to handle
  383. Xnumbers that are near zero, one would have to specify a relative tolerance
  384. Xof 100% which would be unreasonably large when both numbers are non-zero.
  385. X.FE
  386. XIn addition, the user can specify an infinite tolerance.  This is useful
  387. Xfor checking the format of output while ignoring the actual numbers
  388. Xproduced.
  389. X.SH
  390. XAltering the Differencing Algorithm
  391. X.PP
  392. XBy default, 
  393. X.B
  394. Xspiff
  395. X.R
  396. Xproduces a minimal edit sequence (using the Miller/Myers differencing algorithm[4])
  397. Xthat will convert the first file into the second.
  398. XHowever, a minimal edit sequences is not always desirable. 
  399. XFor example, for the following two tables of numbers:
  400. X.DS
  401. X0.1   0.2   0.3                0.2   0.3   0.4
  402. X0.4   0.5   0.6                0.5   0.6   0.7
  403. X.DE
  404. Xa minimal edit sequence to convert the table on
  405. Xthe left into the table on the right be to
  406. Xwould delete the first number (0.1) and insert 0.7 at the end.\**
  407. X.FS
  408. XThe problem of having the elements of tables become misaligned when
  409. Xthe differencing algorithm is trying
  410. Xto find a minimal number of edits can be reduced somewhat
  411. Xby retaining newlines and not using tolerances.
  412. XUnfortunately, it does not go away.
  413. X.FE
  414. XSuch a result, while logically correct, does not provide a good picture
  415. Xof the differences between the two files.
  416. XIn general, for text with a very definite structure (such as tables),
  417. Xwe may not want to consider insertions and deletions at all, but
  418. Xonly one-to-one changes.\**
  419. X.FS
  420. XA "change" can be expressed as one deletion and one insertion at the same
  421. Xpoint in the text.
  422. X.FE
  423. XSo, rather than look for a minimal edit script, we
  424. Xmerely want to compare each token in the first file with
  425. Xthe corresponding token in the second file.
  426. X.PP
  427. XThe user can choose which differencing algorithm to use
  428. X(the default Miller/Myers or
  429. Xthe alternative one-to-one comparison)
  430. Xbased upon what is known about the input files. In general,
  431. Xfiles produced mechanically
  432. X(such the output from test suites) have a very regular structure
  433. Xand the one-to-one comparison works surprisingly well.
  434. XFor files created by humans, the Miller/Myers
  435. Xalgorithm is more appropriate.
  436. XThere is nothing in
  437. X.B
  438. Xspiff's
  439. X.R
  440. Xinternal design that limits
  441. Xthe number of differencing algorithms that it can run.
  442. XOther differencing algorithms,
  443. Xin particular the one used in
  444. X.B
  445. Xdiff,
  446. X.R
  447. Xwill probably be added later.
  448. X.SH
  449. XAltering the Granularity of the Edit Sequence
  450. X.PP
  451. XBy default,
  452. X.B
  453. Xspiff
  454. X.R
  455. Xproduces an edit sequence
  456. Xin terms of insertions and deletions of individual tokens.
  457. XAt times it may be more useful to
  458. Xtreat the contents of the files as tokens when looking for differences
  459. Xbut
  460. Xexpress the edit script in terms of entire lines of the files rather
  461. Xthan individual tokens.\**
  462. X.FS
  463. XFor instance, if one wants to have 
  464. X.B
  465. Xspiff
  466. X.R
  467. Xproduce output that can be fed into
  468. Xthe
  469. X.B
  470. Xed
  471. X.R
  472. Xeditor.
  473. X.FE
  474. X.B
  475. XSpiff
  476. X.R
  477. Xprovides a facility for restricting the edits to entire lines.
  478. X.SH
  479. XTreating Parts of the Files Differently
  480. X.PP
  481. XFor complex input files, it is important that different parts of the
  482. Xfile be treated in different ways.  In other words, it may be impossible
  483. Xto find one set of parsing/differencing rules that work well for the
  484. Xentire file.
  485. X.B
  486. XSpiff
  487. X.R
  488. Xcan differentiate between parts of the input files on two bases:
  489. Xwithin a line and between lines.
  490. XWithin a line, a different tolerance can be applied to each real number.
  491. XThe tolerances are specified in terms of the ordinal position of the
  492. Xnumbers on the line (i.e. one tolerance is applied to the first real number
  493. Xon each line, a different tolerance is applied to the second number on
  494. Xeach line, a third tolerance is applied to the third, and so on).  If more
  495. Xnumbers appear on a line than there are tolerances specified, the last
  496. Xtolerance is applied to all subsequent numbers on the line (i.e., if the user
  497. Xspecifies three tolerances, the third is applied to the third, fourth
  498. Xfifth, . . . number on each line).  This feature is useful for applying
  499. Xdifferent tolerances to the different columns of a table of numbers.
  500. X.PP
  501. XBetween lines, the user can place "embedded commands" in the input files.
  502. XThese commands
  503. Xare instructions to parser that can change what tolerances are attached
  504. Xto real numbers and the commenting and literal string conventions used by the
  505. Xparser.  Embedded commands are flagged to the parser
  506. Xby starting the line with a user-specified
  507. Xescape string.  By combining within line and between line differentiation,
  508. Xit is possible for the user to specify a different tolerance
  509. Xfor every single real number in the input files.
  510. X.SH
  511. XVisual Mode
  512. X.PP
  513. XSo far,
  514. X.B
  515. Xspiff's
  516. X.R
  517. Xoperation as an intelligent filter has been described.
  518. X.B
  519. XSpiff
  520. X.R
  521. Xalso has an interactive mode.
  522. XWhen operating in interactive mode,
  523. X.B
  524. Xspiff
  525. X.R
  526. Xplaces corresponding sections of the input files 
  527. Xside by side on user's screen.\**
  528. X.FS
  529. XAlthough the current implementation of
  530. X.B
  531. Xspiff
  532. X.R
  533. Xruns in many environments,
  534. Xinteractive mode works only under the MGR window manager.[5]
  535. XOther graphics interfaces will probably be added over time.
  536. X.FE
  537. XTokens are compared using a one-to-one ordinal comparison, and any tokens that
  538. Xare found to be different are highlighted in reverse video.
  539. XThe user can interactively change the tolerances and 
  540. X.B
  541. Xspiff
  542. X.R
  543. Xwill alter the display
  544. Xto reflect which real numbers exceed the new tolerances.
  545. XOther commands allow the user to page through the file and exit.
  546. X.SH
  547. XPerformance
  548. X.PP
  549. XTwo components of 
  550. X.B
  551. Xspiff,
  552. X.R
  553. Xthe parser and the differencing algorithm,
  554. Xaccount for most of the execution time.  Miller and Myers compare their
  555. Xalgorithm to the one used in the diff program.  To restate their results,
  556. Xthe Miller/Myers algorithm is faster for files
  557. Xthat have relatively few differences but much
  558. Xslower (quadratic time) for files with a great many differences.
  559. X.PP
  560. XFor cases where the files do not differ greatly,
  561. Xparsing the input files takes most of the time (around 80% of the total).\**
  562. X.FS
  563. XNo effort has yet been made to make the parser run more quickly.
  564. XA faster parser could no doubt be written by generating a special state machine.
  565. X.FE
  566. XThe performance of the parser is roughly similar to programs that do a similar
  567. Xlevel of parsing (i.e. programs that must examine each character in the file).
  568. XFor files where roughly half of the tokens are real numbers, 
  569. X.B
  570. Xspiff
  571. X.R
  572. Xtakes about twice as long to parse the input files
  573. Xas an
  574. X.B
  575. Xawk
  576. X.R
  577. Xprogram that counts the number of words in a file:\**
  578. X.FS
  579. XFor
  580. X.B
  581. Xawk,
  582. X.R
  583. Xa word is any string separated by white space.
  584. X.FE
  585. X.B
  586. X.DS
  587. Xawk '{total += NF}' firstfile secondfile
  588. X.DE
  589. X.R
  590. X.PP
  591. XThe time that it takes 
  592. X.B
  593. Xspiff
  594. X.R
  595. Xto parse a file is substantially
  596. Xincreased if scanning is done for comments
  597. Xand delimited literal strings.  The precise effect depends upon the length of
  598. Xthe delimiters, whether they are restricted to appear at beginning of line, and
  599. Xthe frequency with which literals and comments appear in the input files.
  600. XAs an example, adding the 12 literal conventions\**
  601. X.FS
  602. XOne literal convention is for C literal strings.  The rest enumerate multicharacter
  603. Xoperators.
  604. X.FE
  605. Xand 1 commenting convention
  606. Xrequired for C code roughly doubles the time required to parse input files.\**
  607. X.FS
  608. XSo in total, it takes 
  609. X.B
  610. Xspiff
  611. X.R
  612. Xabout 4 times longer to parse a C program than it takes
  613. X.B
  614. Xawk
  615. X.R
  616. Xto count the number of words in the same file.
  617. X.FE
  618. X.PP
  619. XA more complete approach to evaluating
  620. X.B
  621. Xspiff's
  622. X.R
  623. Xperformance must measure the total time that it takes for the user to complete a
  624. Xdifferencing task.  For example, consider one of the
  625. Xtest suites for the S statistical
  626. Xanalysis package mentioned at the beginning of this paper.
  627. XThe output file for each machine is 427 lines long and contains
  628. X1090 floating point numbers.  It takes
  629. X.B
  630. Xdiff 
  631. X.R
  632. Xapproximately 2 seconds on one of our "6 MIPS"\** computers
  633. X.FS
  634. XWe will not comment on the usefulness of "MIPS" as a measure
  635. Xof computing speed.  The numbers provided are only intended to
  636. Xgive the reader some vague idea of how fast these programs run. 
  637. X.FE
  638. Xto compare the two files and produce
  639. Xan edit script that is 548 lines long containing 1003 "differences"
  640. Xin the floating point numbers.  It takes the average tester
  641. X5 minutes to print out the edit script and roughly 2 hours to examine
  642. Xthe output by hand to determine that the machines are, in fact,
  643. Xboth giving nearly identical answers.  The total time needed is
  644. X2 hours 5 minutes and 2 seconds.
  645. X.PP
  646. XIn contrast, it takes
  647. X.B
  648. Xspiff
  649. X.R
  650. Xapproximately 6 seconds on one of our "6 MIPS" computers to
  651. Xproduce an output file that is 4 lines long.\**
  652. X.FS
  653. XThe output would be zero length except that the output of the
  654. X.B
  655. Xtime
  656. X.R
  657. Xcommand is built into the S tests.
  658. XThe timing information could easily be ignored using
  659. X.B
  660. Xspiff's
  661. X.R
  662. Xembedded commands. But, as we shall see, it hardly seems worth the trouble.
  663. X.FE
  664. XIt takes the average tester 30 seconds to examine
  665. X.B
  666. Xspiff's
  667. X.R
  668. Xoutput.  The total for
  669. X.B
  670. Xspiff
  671. X.R
  672. Xis 36 seconds.  Therefore for this case, 
  673. X.B
  674. Xspiff
  675. X.R
  676. Xwill get the job done roughly 208.88 times faster than
  677. X.B
  678. Xdiff.
  679. X.R
  680. X.PP
  681. XIn general, it is misleading to compare
  682. X.B
  683. Xspiff's
  684. X.R
  685. Xspeed with that of
  686. X.B
  687. Xdiff.
  688. X.R
  689. XWhile both programs are looking for differences between files,
  690. Xthey operate on very different types of data (tokens vs. bytes).
  691. XAn analogous comparison could be made between the speed of an assembler
  692. Xand the speed of a C compiler.  They are both language translators.
  693. XOne runs much faster than the other.
  694. XNone the less, most programmers use the slower program
  695. Xwhenever possible.
  696. X.SH
  697. XUsing Spiff For Making Regression Tests Of Software
  698. X.PP
  699. XWe envision 
  700. X.B
  701. Xspiff
  702. X.R
  703. Xto be the first of several tools for aiding in the now
  704. Xarduous task of making regression tests.\**
  705. X.FS
  706. XIn software engineering parlance, a "regression test" is the process by
  707. Xwhich a tester checks to make sure that the new version of a piece of
  708. Xsoftware still performs the same way as the older versions 
  709. Xon overlapping tasks.
  710. X.FE
  711. XGiven 
  712. X.B
  713. Xspiff's
  714. X.R
  715. Xcurrent capabilities, the regression test designer can
  716. Xtake the output of an older version of software and through
  717. Xthe use of literal string and commenting conventions,
  718. Xspecify what parts of the output must remain identical and
  719. Xwhat sections can change completely.  By specifying tolerances, the test
  720. Xdesigner can take into account how much of a difference in floating
  721. Xpoint calculations is acceptable.
  722. X.PP
  723. XThe test designer is also free to
  724. Xedit the output from the older version of the software and add embedded
  725. Xcommands that can instruct 
  726. X.B
  727. Xspiff
  728. X.R
  729. Xto treat various parts of the output
  730. Xdifferently.  The newly edited output can then serve as a template for
  731. Xthe output of later versions of the software.
  732. X.PP
  733. XObviously, editing output by hand is a very low level mechanism for adding
  734. Xspecification information.  It is our intention that 
  735. X.B
  736. Xspiff
  737. X.R
  738. Xwill become
  739. Xthe last element in a pipeline of programs.  Programs (as yet unwritten) located
  740. Xearlier in the pipeline
  741. Xcan implement a higher level representation of the specification information.
  742. XThey read in the old and new input files, add the appropriate embedded commands,
  743. Xand then pass the results to 
  744. X.B
  745. Xspiff
  746. X.R
  747. Xwhich will do the actual differencing.
  748. X.SH
  749. XFuture Work
  750. X.PP
  751. XThere are many features that could be added to 
  752. X.B
  753. Xspiff
  754. X.R
  755. X(if there are not
  756. Xtoo many already).  Some of these include: 
  757. X.IP \(bu
  758. XUsing separate differencing algorithms on separate sections of the file
  759. Xand/or limiting the scope of an edit sequence (fencing) 
  760. X.IP \(bu
  761. XProviding a more general mechanism for specifying comments and literals
  762. X(perhaps allowing specification in terms of regular expressions).
  763. XAs yet, we have not encountered any important cases where regular expressions
  764. Xhave been needed.  Until such a case is encountered, we will leave regular
  765. Xexpressions out in the name of simplicity.
  766. X.IP \(bu
  767. XAllowing for a more general specification of what lines should look like.
  768. XAt present, the user can only specify tolerances for numbers as a function
  769. Xof their ordinal position on a line.  The difficulty in expanding the
  770. Xspecification abilities of 
  771. X.B
  772. Xspiff
  773. X.R
  774. Xis knowing when to stop.  In the extreme,
  775. Xwe might add all of the functionality of a program such as
  776. X.B
  777. Xawk.\**
  778. X.R
  779. X.FS
  780. XImagine handling the case such as
  781. X"apply this tolerance to all numbers that appear
  782. Xon a line starting with the word `foo' but only if the number is between 1.9
  783. Xand 3.6 and the word `bar' does not appear on the line".
  784. X.FE
  785. XWe hope to keep 
  786. X.B
  787. Xspiff
  788. X.R
  789. Xas simple as possible.  Our first efforts in
  790. Xthis direction will try to implement higher level specification functions
  791. Xoutside of 
  792. X.B
  793. Xspiff.
  794. X.R
  795. X.SH
  796. XAcknowledgements
  797. X.PP
  798. XFirst and foremost, we thank Stu Feldman for his endless patience, constant encouragement
  799. Xand numerous good ideas. We also extend thanks to Doug McIlroy for bringing the Miller/Myers
  800. Xalgorithm to our attention, Nat Howard for a key insight
  801. Xand for his editorial comments
  802. Xand Steve Uhler and Mike Bianchi for their editorial comments.
  803. X.SH
  804. XReferences
  805. X.IP [1]
  806. XHunt,J.W. and M.D. McIlroy.
  807. X.I
  808. XAn Algorithm For Differential File Comparisons, 
  809. X.R
  810. X.B
  811. XBell Labs Computer Science Technical Report,
  812. X.R
  813. XNumber 41, 1975.
  814. X.IP [2]
  815. XBecker,R.A. and J.M. Chambers (1984).
  816. X.B
  817. XS \- An Interactive Environment For Data Analysis And
  818. XGraphics.
  819. X.R
  820. XBelmont, CA: Wadsworth Inc.
  821. X.IP [3]
  822. XWatterson, B. (1987).
  823. X.B
  824. XCalvin and Hobbes.
  825. X.R
  826. XNew York: Andrews, McMeel & Parker.
  827. X.IP [4]
  828. XMiller, W. and E.W. Myers.
  829. X.I
  830. XA File Comparison Program,
  831. X.R
  832. X.B
  833. XSoftware \-
  834. XPractice and Experience
  835. X.R
  836. X15, 11, 1025-1040, 1985.
  837. X.IP [5]
  838. XUhler, S.A.
  839. X.I
  840. XMGR -- A Window Manager For UNIX,
  841. X.R
  842. XSun User's Group Meeting. September 1986.
  843. X.LP
  844. END_OF_FILE
  845. if test 25154 -ne `wc -c <'paper.ms'`; then
  846.     echo shar: \"'paper.ms'\" unpacked with wrong size!
  847. fi
  848. # end of 'paper.ms'
  849. fi
  850. echo shar: End of archive 4 \(of 4\).
  851. cp /dev/null ark4isdone
  852. MISSING=""
  853. for I in 1 2 3 4 ; do
  854.     if test ! -f ark${I}isdone ; then
  855.     MISSING="${MISSING} ${I}"
  856.     fi
  857. done
  858. if test "${MISSING}" = "" ; then
  859.     echo You have unpacked all 4 archives.
  860.     rm -f ark[1-9]isdone
  861. else
  862.     echo You still need to unpack the following archives:
  863.     echo "        " ${MISSING}
  864. fi
  865. ##  End of shell archive.
  866. exit 0
  867.